********************

  Genesis Game Mod 

********************

Table Of Contents
-----------------

1 - Overview
2 - Usage
3 - Configuration File 
3.1 - Command Reference
3.2 - Examples
4 - Nation Data File
5 - Mod Data File
6 - Additional Information
7 - Known Issues

1 - Overview
------------

This is a utility for Dominions 2 that modifies the game parameters as specified by a user configuration file. The range and depth of these modifications parallel that of game mods themselves. Differing from a game mod, this utility modifies the game in a random, yet controlled, manor so that each time it is run it can create a unique game environment limited only by the Dominions 2 modding commands and the user restrictions placed in the editor. Whether you want a completely random world, or a controlled but unique world, I hope this utility will help you. 

2 - Usage
---------

This utility requires two data files (Nation.Dat, Mod.Dat) and a configuration file (GenGM.CFG) to function correctly. Do not fear though as changing only the configuration file is required to access 95% of the utility's functionality. Only those users wishing to tweak the last 5% need learn how to alter the other files. 

To use this utility to create a new game environment, you simply edit the files if you wish to, then run GenGM.EXE to create a new mod. GenGM can be run by just dbl-clicking on it in Windows. It is normal to execute very quickly. After this start Dominions 2 and make sure the mod labelled "Genesis Forge Version - ???", where ??? represents the base mod presently used by the system (see Mod Data File section for details), is enabled. Now start a new game and enjoy!

3 - Configuration File
----------------------

The configuration file, GenGM.CFG, follows loosely the syntax that Dominions 2 uses for creating mods and in fact some configuration commands require knowledge of the modding commands themselves. It is advised, therefore, that after reading this document to familiarize yourself with the commands in the "Dominions 2 Modding Manual" that interest you. This utility was designed with two key factors in mind: maximizing customization power and minimizing complexity. When in conflict, customization power was chosen. 

The configuration file is divided into two sections. The first section allows you to specify mods and place them into various categories. There are two types of categories: Global and National. The mods in global categories do not apply to any nation specifically but instead modify some global game parameter (such as spells). The mods in national categories however do apply just to nations and modify some national parameter (such as starting sites, adding new units, or altering existing units). 

The second section allows you to specify how many mods the utility will pick at random from each category to create the overall resulting game mod. The number of random picks from global categories are specified once whereas the number of random picks from national categories are specified for each nation separately thereby allowing various nations to get different numbers of picks from each category. 

The command reference section provides information on all the configuration commands available and the example section shows their use in a template format that you can modify for use in your own configurations. GenGM.CFG is a simple text file that any text editor can modify. You specify all commands by preceding them with a #. Any line that does not contain a # key is ignored. 


3.1 - Command Reference
-----------------------

NewCategory
-----------

SYNTAX:

#NewCategory CategoryNumber CategoryType

DESCIRPTION:

This command defines a new category. CategoryNumber is a number between 0 - 25, inclusive, that identifies the new category. CategoryType is one of two values, 1 or 2, where 1 defines the category as global and 2 defines it as national. Further all subsequent NewMod commands will apply to this category until the next NewCategory command. 

ADDITIONAL NOTES:

NewMod
------

SYNTAX:

#NewMod ModType

DESCIRPTION:

This command defines a new mod and adds it to the category identified by last NewCategory command. To use this command without first preceding it by a NewCategory command is an error. When adding a mod to a global category, ModType is ignored. However when adding a mod to a national category, Mod Type specifies which aspect of the nation will be modified. The meaning of the following values are defined:

1 - Units
2 - Commanders
3 - Units and Commanders
4 - Mages
5 - Units and Mages
6 - Commanders and Mages
7 - Units, Commanders, and Mages
8 - General

Values 1 - 7 specify that a nation's units of the specified types will modified by this mod whereas value 8 specifies that no units but some other general aspect of the nation will be modified (such as adding a new unit or starting site).

All subsequent mod definition commands will apply to this mod until the next NewMod or NewCategory command.

ADDITIONAL NOTES:

Note although, of course, all mages are commanders, I separated them into two categories so that they could be modded independently.

Custom
------

SYNTAX:

#Custom [Custom Mod Text]

DESCIRPTION:

This is, at present, the only mod definition command defined. Future releases will add in additional definition commands. It is the only command but is also the most powerful. This command defines the mod specified by the last NewMod command. To use this command without first preceding it by a NewMod command is an error. 

Custom Mod Text represents one or more of the Dominions 2 mod commands that make up this configuration file mod. Any mod commands appropriate to the type of mod and category are allowed within this text. This text is interpreted as it would be by the Dominions 2 Mod engine without the square brackets, when placed in proper context determined by the mod type. 

As this command is very versatile, the details of its use are rather numerous. Detailing them directly would be difficult and ultimately ineffectual in conveying they meaning. Therefore for further info refer to the example section that should clarify its use. 

ADDITIONAL NOTES:

When modifying nations with this command, mod commands / tags such as #selectmonster and #end should NOT be included. The utility itself knows the units of a particular nation and provides these context tags automatically. Including them will only result in duplication and hence unintended behaviour. 

Nation
------

SYNTAX:

#Nation NationNumber

DESCIRPTION:

This command selects the current nation, as specified by NationNumber. Subsequent, nation dependent commands will apply to this nation. Each of the 17 nations in the game must have an association #Nation command in the configuration file. 

The NationNumber is the same as those specified in the modding manual and simply specifies which nation the command pertains to. For reference I have included this list inside the GenMM.CFG file distributed.

ADDITIONAL NOTES:

RandomPickCount
---------------

SYNTAX:

#RandomPickCount CategoryNumber PickCount

DESCIRPTION:

This command is used to specify how many of the mods in a particular category to select when creating a game mod. 

CategoryNumber is the same as that used in the NewCategory command, and identifies which category this command pertains to. If this category is a global category, this command is contextless (i..e can be issued anywhere). However if this category is a national category, this command only applies to the nation defined by a preceding Nation command. In this case, issuing this command without preceding it by a #Nation command is an error. 

PickCount indicates the number of random picks for the utility to choose from that category, either globally or for the current nation. Thus different nations can have different number of picks from national categories.

ADDITIONAL NOTES:

3.2 - Examples
--------------

Example 1
---------

This example will be a walkthrough to create a configuration file from scratch. In this walkthrough suppose we want to create a game mod with the following requirements:

A. Either one of the following is applied:
	- Flaming Arrows costs 20 fatigue and does not require a fire gem
	- Storm costs 20 fatigue and does not require an air gem. 
B. All nations gain a supplybouns of 20 for their commanders to prevent starving.
C. All units for T'ien Chi and Ulm each gain two of the following:
	- Shock Resistance
	- Fire Resistance
	- Cold Resistance
	- 20% Regeneration
D. Add a recruitable Vampire Queen to Ermor

To do this we will need 4 categories, 1 global and 3 national. The category definition code follows:

#NewCategory 1 1

#NewMod 8
#Custom 
[
#selectspell "Flaming Arrows"
#fatiguecost 20
#end
]

#NewMod 8
#Custom
[
#selectspell "Storm"
#fatiguecost 20
#end
]

#NewCategory 2 2
#NewMod 2
#Custom [#supplybonus 20]

#NewCategory 3 2
#NewMod 7
#Custom [#shockres 100]

#NewMod 7
#Custom [#fireres 100]

#NewMod 7
#Custom [#coldres 100]

#NewMod 7
#Custom [#regeneration 20]

#NewCategory 4 2
#NewMod 8
#Custom [#addreccom 862]

With the categories defined, we now must set the appropriate number of random picks with the following code:

#RandomPickCount 1 1

#Nation 0
#RandomPickCount 2 1

#Nation 1
#RandomPickCount 2 1

#Nation 2
#RandomPickCount 2 1

#Nation 3
#RandomPickCount 2 1

#Nation 4
#RandomPickCount 2 1
#RandomPickCount 3 2

#Nation 5
#RandomPickCount 2 1

#Nation 6
#RandomPickCount 2 1

#Nation 7
#RandomPickCount 2 1

#Nation 8
#RandomPickCount 2 1
#RandomPickCount 4 1

#Nation 9
#RandomPickCount 2 1

#Nation 10
#RandomPickCount 2 1

#Nation 11
#RandomPickCount 2 1

#Nation 12
#RandomPickCount 2 1

#Nation 13
#RandomPickCount 2 1

#Nation 14
#RandomPickCount 2 1

#Nation 15
#RandomPickCount 2 1
#RandomPickCount 3 2

#Nation 16
#RandomPickCount 2 1

Combine this code together in a file, name that file GenGM.CFG, and run GenGM.EXE. Your mod is ready. Enable it and away you go!

4 - Nation Data File 
--------------------

Presently altering the Nation.Dat file is not documented. Though enabled, as this is still a beta, I would like users to only alter the configuration file for the time being to narrow down the potential causes of errors. In the near future I will document this section. 

5 - Mod Data File
-----------------

Presently altering the Mod.Dat file is not documented. Though enabled, as this is still a beta, I would like users to only alter the configuration file for the time being to narrow down the potential causes of errors. In the near future I will document this section. 

6 - Additional Information
--------------------------

The following notes should allow you to get the most out of this utility:

This utility is limited by the ability to mod Dominions 2 itself so any limitations or unexpected results that occur with regular mods will occur with these mods as well. 

The resulting mod for this utility can conflict with other mods if you enable them both at the same time, as with all other Dominions 2 mods. For example if you disable Flaming Arrows and then also include, say, Zen's Spell Mod, it may give you the desired results or may override your disabling of Flaming Arrows depending upon which mod is used first by Dominions 2. That is not to say that you can't successfully use the generated mod in conjunction with any others but just to be aware of this possible conflict. 

It is recommended that you disable Saber Cherry's Recruitable Rebalance mod when using this utility's mod. This is not because it isn't a good mod but because this utility presently embeds a copy of that mod in its mod. So including it would be redundant and certainly cause conflicts.

7 - Known Issues
----------------

At present there are no known issues - though that doesn't mean much necessarily :).

